##############################################################################
# uv - Python Package Manager 速查表 (uv Cheatsheet)
# 一个极其快速的 Python 包安装程序和解析器，旨在替代 pip 和 venv。
# https://github.com/funnyzak/cli-cheatsheets
##############################################################################

# 图例 (Legend):
#   - <package>:         包名 (e.g., requests, "django>=4.0")
#   - <requirement_file>: 需求文件名 (e.g., requirements.txt, pyproject.toml)
#   - <venv_dir>:        虚拟环境目录名 (默认: .venv)
#   - <python_version>:  Python 版本 (e.g., 3.11, python3.10)
#   - <command>:         要在虚拟环境中执行的命令
#   - <script.py>:       要执行的 Python 脚本

##############################################################################
# 通用选项 (General Options)
##############################################################################

uv --version                     # 显示 uv 版本
uv --help                        # 显示主帮助信息
uv <subcommand> --help           # 显示子命令的帮助信息 (e.g., uv pip install --help)
uv --verbose                     # 启用详细输出 (或 -v, -vv, -vvv 增加详细程度)
uv --quiet                       # 抑制除错误外的所有输出
uv --native-tls                  # 使用系统的本地 TLS 库 (替代 rustls)
uv --no-cache                    # 禁用所有缓存

##############################################################################
# 虚拟环境管理 (Virtual Environment Management, uv venv)
##############################################################################

uv venv [<venv_dir>]             # 创建虚拟环境 (默认: .venv)
uv venv <venv_dir> -p <python>   # 使用指定 Python 解释器创建虚拟环境
uv venv --seed                   # 创建虚拟环境并安装 pip

# 注意: uv 创建环境后，仍需使用 Shell 的标准方式激活环境:
#   source .venv/bin/activate    # (Bash/Zsh)
#   .venv\Scripts\activate.bat   # (Windows Cmd)
#   .venv\Scripts\Activate.ps1   # (Windows PowerShell)

##############################################################################
# 包安装与管理 (Package Installation & Management, uv pip)
##############################################################################

# 安装包 (Install Packages)
uv pip install <package> [<package>...]      # 安装一个或多个包
uv pip install -r <requirement_file>       # 从需求文件安装包
uv pip install -r req1.txt -r req2.txt     # 从多个需求文件安装
uv pip install -e <path_to_project>        # 以可编辑模式安装本地项目
uv pip install "package[extra]"            # 安装带可选依赖的包
uv pip install <package> --upgrade         # 升级包到最新兼容版本
uv pip install <package> --reinstall       # 重新安装包
uv pip install <package> --no-deps         # 安装包但不安装其依赖

# 卸载包 (Uninstall Packages)
uv pip uninstall <package> [<package>...]    # 卸载一个或多个包
uv pip uninstall -r <requirement_file>     # 卸载需求文件中列出的所有包

# 列出包 (List Packages)
uv pip list                              # 列出已安装的包
uv pip list --outdated                   # 列出可升级的包
uv pip list --editable                   # 仅列出以可编辑模式安装的包
uv pip list --exclude-editable           # 排除以可编辑模式安装的包
uv pip list --format freeze              # 以 requirements.txt 格式输出 (类 pip freeze)
uv pip list --format json                # 以 JSON 格式输出

# 显示包信息 (Show Package Information)
uv pip show <package> [<package>...]       # 显示一个或多个已安装包的详细信息

# 检查依赖 (Check Dependencies)
uv pip check                             # 检查已安装包之间的依赖关系是否满足

##############################################################################
# 依赖管理 (Dependency Management)
##############################################################################

# 同步环境 (Synchronize Environment)
uv pip sync <requirement_file>             # 同步环境，确保仅安装文件中指定的包 (会卸载多余的包)
uv pip sync req1.txt req2.txt              # 从多个文件同步

# 编译/锁定依赖 (Compile/Lock Dependencies)
uv pip compile pyproject.toml -o requirements.txt  # 将 pyproject.toml 依赖解析并锁定到 requirements.txt
uv pip compile requirements.in -o requirements.txt # 将 requirements.in 解析并锁定到 requirements.txt
uv pip compile ... --upgrade             # 尝试升级所有包到最新版本再锁定
uv pip compile ... --resolution=lowest-direct # 使用最低兼容版本解析直接依赖
uv pip compile ... --all-extras          # 包含所有可选依赖进行解析
uv pip compile ... --output-file -       # 将结果输出到标准输出

##############################################################################
# 运行命令/脚本 (Running Commands/Scripts, uv run)
##############################################################################

uv run <command> [args...]           # 在检测到的虚拟环境中执行命令
uv run -- <script.py> [args...]      # 在检测到的虚拟环境中执行 Python 脚本
uv run --python <python> <command>   # 在指定 Python 版本的临时环境中执行命令

# 注意: `uv run` 会自动检测 `.venv` 或 `pyproject.toml` 来确定环境。

##############################################################################
# 缓存管理 (Cache Management, uv cache)
##############################################################################

uv cache clean                           # 清除 uv 缓存
uv cache dir                             # 显示 uv 缓存目录路径

##############################################################################
# 工具命令 (Tool Commands, uv tool) - 管理 uv 本身或相关工具
##############################################################################

# (uv tool 子命令目前较少，未来可能扩展)
# uv tool install <tool_name> [...]   # (假设未来可能有类似 pipx 的功能)
# uv tool list                        # (假设未来可能有列出已安装工具的功能)

##############################################################################
# 实用技巧 (Tips and Tricks)
##############################################################################

# 快速创建环境并安装依赖:
#   uv venv && uv pip install -r requirements.txt
#   # 或者直接从 pyproject.toml (如果定义了 [project.dependencies]):
#   uv venv && uv pip install .

# 使用 pyproject.toml 管理项目依赖:
#   # 在 pyproject.toml 中定义依赖:
#   # [project]
#   # name = "my-package"
#   # version = "0.1.0"
#   # dependencies = [ "requests", "click" ]
#   # [project.optional-dependencies]
#   # test = [ "pytest" ]
#   # 然后运行:
#   uv pip install .          # 安装基本依赖
#   uv pip install ".[test]"  # 安装基本依赖和 test 可选依赖

# 生成锁文件并同步:
#   uv pip compile pyproject.toml -o requirements.lock.txt
#   uv pip sync requirements.lock.txt

# 利用 uv 的速度进行快速原型或测试:
#   uv run --python 3.11 pip install -r requirements-dev.txt && uv run pytest

##############################################################################
# 示例 (Examples)
##############################################################################

# 1. 创建新项目环境并安装 Flask:
#   mkdir my_flask_app && cd my_flask_app
#   uv venv
#   source .venv/bin/activate  # 或者相应的激活命令
#   uv pip install flask
#   uv pip list --format freeze > requirements.txt

# 2. 从 pyproject.toml 安装项目并运行测试:
#   git clone <your_project_repo>
#   cd <your_project_repo>
#   uv venv
#   uv pip install ".[test]"  # 假设 test extra 在 pyproject.toml 中定义
#   uv run pytest

# 3. 编译并同步锁定的依赖:
#   uv pip compile requirements.in -o requirements.txt --upgrade
#   uv pip sync requirements.txt

##############################################################################
# 更多资源 (Further Resources)
##############################################################################

# 官方文档: https://docs.astral.sh/uv/
# GitHub 仓库: https://github.com/astral-sh/uv

# vim: set ts=4 sw=4 tw=0 et ft=bash :